휠(Wheel) 배포 형식: 파이썬용 바이너리 패키지 만들기

파이썬 생태계는 효율적인 패키지 관리에 크게 의존합니다. 이 생태계의 초석 중 하나는 종종 .whl 확장자로 식별되는 휠(Wheel) 배포 형식입니다. 이 가이드는 휠 형식의 복잡성, 장점, 그리고 원활하고 안정적인 소프트웨어 배포를 목표로 하는 전 세계 개발자들을 위해 파이썬용 바이너리 패키지를 만드는 방법을 자세히 설명합니다.

휠(Wheel) 형식이란 무엇인가?

휠 형식은 파이썬용 빌드 패키지 형식입니다. 소스 배포(sdist)보다 더 쉽게 설치되도록 설계되었습니다. 이는 오래된 egg 형식을 대체하며 여러 단점을 해결합니다. 기본적으로 휠은 특정 구조와 메타데이터를 가진 ZIP 아카이브로, pip 및 기타 설치 도구가 소스에서 빌드할 필요 없이 패키지를 신속하게 설치할 수 있게 해줍니다.

휠(Wheel)의 주요 특징

• 플랫폼 독립성 (해당하는 경우): 휠은 특정 플랫폼 및 아키텍처(예: Windows 64비트, Linux x86_64)용으로 빌드되거나 플랫폼 독립적(순수 파이썬)일 수 있습니다. 이를 통해 다양한 운영 체제에 최적화된 바이너리를 생성할 수 있습니다.
• 쉬운 설치: 휠 형식에는 사전 빌드된 배포판이 포함되어 있어 설치 중 코드 컴파일 필요성을 최소화합니다. 이는 특히 C 확장 프로그램이나 다른 컴파일된 구성 요소가 있는 패키지의 설치 속도를 크게 향상시킵니다.
• 메타데이터 포함: 휠은 의존성, 버전 정보, 진입점 등 패키지에 대한 모든 필수 메타데이터를 포함합니다. 이 메타데이터는 pip와 같은 패키지 관리자가 의존성을 처리하고 패키지를 올바르게 설치하는 데 매우 중요합니다.
• 원자적 설치: pip는 휠에서 패키지를 원자적으로 설치합니다. 이는 설치가 성공적으로 완료되거나 완전히 롤백되어 불일치를 유발할 수 있는 부분적으로 설치된 패키지를 방지함을 의미합니다.
• 재현성: 휠은 대상 플랫폼이 일치한다고 가정할 때 재컴파일 없이 여러 환경에 걸쳐 설치할 수 있는 일관된 빌드 결과물을 제공하여 재현성을 향상시킵니다.

왜 휠(Wheel)을 사용해야 하는가?

소스 배포 대신 휠을 선택하면 수많은 이점이 있으며 패키지 설치 및 배포 프로세스를 간소화합니다. 주요 이점은 다음과 같습니다:

더 빠른 설치 시간

휠의 가장 큰 장점 중 하나는 속도입니다. 사전 빌드된 배포판을 제공함으로써 휠은 설치 중 코드 컴파일 필요성을 없애줍니다. 이는 C, C++ 또는 기타 언어로 작성된 컴파일된 확장 프로그램이 있는 패키지에 특히 유용합니다. 복잡한 과학 라이브러리를 배포한다고 상상해보세요. 휠을 사용하면 최종 사용자 컴퓨터의 설치 시간이 크게 단축됩니다.

예시: 소스에서 numpy를 설치하는 것은 특히 오래된 하드웨어에서 몇 분이 걸릴 수 있습니다. 휠에서 설치하는 것은 일반적으로 몇 초밖에 걸리지 않습니다.

빌드 도구에 대한 의존성 감소

소스에서 패키지를 설치하려면 사용자가 시스템에 필요한 빌드 도구(컴파일러, 헤더 등)를 설치해야 하는 경우가 많습니다. 이는 특히 소프트웨어 개발에 익숙하지 않은 사용자에게 진입 장벽이 될 수 있습니다. 휠은 이러한 의존성을 제거하여 설치를 더 간단하고 접근하기 쉽게 만듭니다.

예시: 연구실의 데이터 과학자는 소스에서 패키지를 빌드하는 데 필요한 컴파일러가 없을 수 있습니다. 휠을 사용하면 환경을 구성할 필요 없이 패키지를 직접 설치할 수 있습니다.

향상된 신뢰성

사전 빌드된 바이너리를 제공함으로써 휠은 패키지가 여러 환경에서 일관된 방식으로 설치되도록 보장합니다. 이는 시스템 구성이나 빌드 도구 버전의 차이로 인한 설치 오류 위험을 줄여줍니다. 이러한 일관성은 안정적이고 예측 가능한 동작을 요구하는 애플리케이션에 매우 중요합니다.

예시: 여러 서버에 배포된 웹 애플리케이션은 일관된 패키지 버전을 가져야 합니다. 휠을 사용하면 각 서버에 동일한 바이너리가 설치되도록 보장하여 배포 문제의 위험을 최소화합니다.

강화된 보안

휠은 진위와 무결성을 확인하기 위해 서명될 수 있습니다. 이는 악의적인 행위자가 변조된 패키지를 배포하는 것을 방지하는 데 도움이 됩니다. 패키지 서명은 추가적인 보안 계층을 제공하여 사용자가 신뢰할 수 있는 소프트웨어를 설치하도록 보장합니다.

예시: 조직은 프로덕션 환경에 배포되기 전에 모든 패키지에 서명하도록 요구하는 정책을 구현할 수 있습니다. 이는 악성 코드가 패키지에 주입되는 공급망 공격으로부터 보호합니다.

휠 패키지 만들기: 단계별 가이드

휠 패키지를 만드는 것은 setuptools와 wheel 패키지를 사용하는 간단한 과정입니다. 다음은 자세한 가이드입니다:

1. 프로젝트 설정하기

먼저, 프로젝트가 올바르게 구조화되었는지 확인하세요. 최소한 setup.py 파일과 패키지의 소스 코드가 필요합니다.

프로젝트 구조 예시:

my_package/
 ├── my_module/
 │   ├── __init__.py
 │   └── my_function.py
 ├── setup.py
 └── README.md

2. setup.py 파일

setup.py 파일은 프로젝트의 핵심입니다. 패키지에 대한 메타데이터를 포함하고 빌드 및 설치 방법을 정의합니다. 다음은 setup.py 파일의 예시입니다:

from setuptools import setup, find_packages

setup(
 name='my_package',
 version='0.1.0',
 description='A simple example package',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/your_username/my_package',
 author='Your Name',
 author_email='your.email@example.com',
 license='MIT',
 packages=find_packages(),
 install_requires=['requests'],
 classifiers=[
 'Development Status :: 3 - Alpha',
 'Intended Audience :: Developers',
 'License :: OSI Approved :: MIT License',
 'Programming Language :: Python :: 3',
 'Programming Language :: Python :: 3.6',
 'Programming Language :: Python :: 3.7',
 'Programming Language :: Python :: 3.8',
 'Programming Language :: Python :: 3.9',
 ],
)

주요 필드 설명:

• name: 패키지의 이름입니다. 사용자가 패키지를 설치할 때 사용할 이름입니다(예: pip install my_package).
• version: 패키지의 버전 번호입니다. 일관된 버전 관리 관행을 위해 시맨틱 버저닝(SemVer)을 따르세요(예: 0.1.0, 1.0.0, 2.5.1).
• description: 패키지에 대한 간단한 설명입니다.
• long_description: 패키지에 대한 자세한 설명입니다. 종종 README.md 파일에서 읽어옵니다.
• url: 패키지의 홈페이지 또는 저장소 URL입니다.
• author: 패키지 작성자의 이름입니다.
• author_email: 패키지 작성자의 이메일 주소입니다.
• license: 패키지가 배포되는 라이선스입니다(예: MIT, Apache 2.0, GPL).
• packages: 배포에 포함할 패키지 목록입니다. find_packages()는 프로젝트의 모든 패키지를 자동으로 찾습니다.
• install_requires: 패키지에 필요한 의존성 목록입니다. pip는 패키지가 설치될 때 이러한 의존성을 자동으로 설치합니다.
• classifiers: 사용자가 PyPI(Python Package Index)에서 패키지를 찾는 데 도움이 되는 메타데이터입니다. 이 분류자는 개발 상태, 대상 고객, 라이선스 및 지원되는 파이썬 버전을 설명합니다.

3. wheel 설치하기

wheel 패키지가 설치되어 있지 않다면 pip를 사용하여 설치할 수 있습니다:

pip install wheel

4. 휠 패키지 빌드하기

프로젝트의 루트 디렉터리(setup.py가 있는 곳)로 이동하여 다음 명령을 실행하세요:

python setup.py bdist_wheel

이 명령은 휠 패키지(.whl 파일)와 소스 배포판(.tar.gz 파일)을 포함하는 dist 디렉터리를 생성합니다.

5. 휠 파일 찾기

생성된 휠 파일은 dist 디렉터리에 위치합니다. 파일 이름은 package_name-version-pyXX-none-any.whl 형식을 따르며, 여기서 각 부분은 다음과 같습니다:

• package_name: 패키지의 이름입니다.
• version: 패키지의 버전 번호입니다.
• pyXX: 패키지가 호환되는 파이썬 버전입니다(예: py37는 파이썬 3.7).
• none: 패키지가 플랫폼에 특정되지 않았음을 나타냅니다.
• any: 패키지가 모든 아키텍처와 호환됨을 나타냅니다.

플랫폼별 휠의 경우 none 및 any 태그는 플랫폼 및 아키텍처 식별자(예: Windows 64비트의 경우 win_amd64)로 대체됩니다.

6. 휠 패키지 테스트하기

휠 패키지를 배포하기 전에 올바르게 설치되는지 테스트하는 것이 중요합니다. pip를 사용하여 이 작업을 수행할 수 있습니다:

pip install dist/my_package-0.1.0-py39-none-any.whl

dist/my_package-0.1.0-py39-none-any.whl을 실제 휠 파일 경로로 바꾸세요.

7. 휠 패키지 배포하기

휠 패키지를 빌드하고 테스트한 후에는 다양한 채널을 통해 배포할 수 있습니다:

• PyPI (Python Package Index): 파이썬 패키지를 배포하는 가장 일반적인 방법입니다. twine을 사용하여 PyPI에 휠 패키지를 업로드할 수 있습니다.
• 사설 패키지 인덱스: 조직 내 내부 사용을 위해 devpi나 Artifactory와 같은 도구를 사용하여 사설 패키지 인덱스를 설정할 수 있습니다.
• 직접 배포: 이메일, 파일 공유 또는 기타 수단을 통해 사용자에게 휠 패키지를 직접 배포할 수도 있습니다.

C 확장 및 플랫폼별 휠 처리하기

플랫폼별 휠, 특히 C 확장을 포함하는 휠을 만들려면 추가 단계가 필요합니다. 다음은 그 과정에 대한 개요입니다:

1. C 확장 컴파일하기

C 확장은 각 대상 플랫폼에 맞게 컴파일해야 합니다. 이 과정은 일반적으로 C 컴파일러(예: GCC, MSVC)와 플랫폼별 빌드 도구를 사용합니다.

예시: Windows에서는 C 확장을 빌드하기 위해 Microsoft Visual C++ 컴파일러를 사용해야 합니다. Linux에서는 일반적으로 GCC를 사용합니다.

2. cffi 또는 Cython 사용하기

cffi나 Cython과 같은 도구는 C 확장을 만드는 과정을 단순화할 수 있습니다. cffi를 사용하면 C 코드를 직접 작성하지 않고도 파이썬에서 C 코드를 호출할 수 있으며, Cython을 사용하면 C 확장으로 컴파일되는 C와 유사한 코드를 작성할 수 있습니다.

3. 플랫폼별 의존성 정의하기

setup.py 파일에서 setup_requires 및 install_requires 매개변수를 사용하여 플랫폼별 의존성을 정의할 수 있습니다. 이를 통해 플랫폼마다 다른 의존성을 지정할 수 있습니다.

예시:

from setuptools import setup, Extension
import platform

if platform.system() == 'Windows':
 extra_compile_args = ['/O2', '/EHsc']
else:
 extra_compile_args = ['-O3']

setup(
 name='my_package',
 version='0.1.0',
 ext_modules=[
 Extension(
 'my_package.my_extension',
 ['my_package/my_extension.c'],
 extra_compile_args=extra_compile_args,
 ),
 ],
)

4. 플랫폼별 휠 빌드하기

플랫폼별 휠을 빌드하려면 각 대상 플랫폼에 적합한 빌드 환경을 사용해야 합니다. 여기에는 가상 머신이나 Docker와 같은 컨테이너 기술을 사용하는 것이 포함될 수 있습니다.

예시: Windows 64비트용 휠을 빌드하려면 Microsoft Visual C++ 컴파일러가 설치된 Windows 64비트 시스템에서 빌드 프로세스를 실행해야 합니다.

휠 패키지 생성을 위한 모범 사례

모범 사례를 따르면 휠 패키지가 신뢰할 수 있고 유지 관리가 용이하며 사용하기 쉬워집니다. 다음은 몇 가지 주요 권장 사항입니다:

1. 시맨틱 버저닝(SemVer) 사용하기

일관된 버전 관리 관행을 위해 시맨틱 버저닝(SemVer)을 따르세요. SemVer는 세 부분으로 된 버전 번호(MAJOR.MINOR.PATCH)를 사용하여 각 릴리스의 변경 유형을 나타냅니다.

• MAJOR: 호환되지 않는 API 변경을 나타냅니다.
• MINOR: 하위 호환성을 유지하는 새로운 기능을 나타냅니다.
• PATCH: 하위 호환성을 유지하는 버그 수정을 나타냅니다.

예시: 기존 코드를 손상시키는 방식으로 함수의 매개변수를 변경하면 주 버전 번호를 올려야 합니다(예: 1.0.0에서 2.0.0으로). 기존 함수를 변경하지 않고 새 함수를 추가하면 부 버전 번호를 올려야 합니다(예: 1.0.0에서 1.1.0으로). 버그를 수정하면 수 버전 번호를 올려야 합니다(예: 1.0.0에서 1.0.1로).

2. README.md 파일 포함하기

설치 지침, 사용 예시, 기여 가이드라인을 포함하여 패키지에 대한 자세한 설명을 제공하는 README.md 파일을 포함하세요. 이는 사용자가 패키지 사용법을 이해하고 기여를 장려하는 데 도움이 됩니다.

3. 명확하고 간결한 문서 작성하기

API 문서, 튜토리얼, 예제를 포함하여 패키지에 대한 명확하고 간결한 문서를 작성하세요. Sphinx나 Read the Docs와 같은 도구를 사용하여 코드 주석에서 문서를 생성하세요.

4. 라이선스 사용하기

패키지를 사용, 수정 및 배포할 수 있는 조건을 명확하게 정의하는 라이선스를 선택하세요. 일반적인 라이선스로는 MIT, Apache 2.0, GPL이 있습니다.

5. 패키지를 철저히 테스트하기

pytest나 unittest와 같은 자동화된 테스트 도구를 사용하여 패키지를 철저히 테스트하세요. 단위 테스트, 통합 테스트, 종단 간 테스트를 작성하여 패키지가 다양한 시나리오에서 올바르게 작동하는지 확인하세요.

6. 지속적 통합(CI) 사용하기

GitHub Actions, GitLab CI, Jenkins와 같은 지속적 통합(CI) 도구를 사용하여 코드베이스에 변경 사항이 있을 때마다 패키지를 자동으로 빌드하고 테스트하세요. 이는 버그를 조기에 발견하고 패키지가 항상 작동 상태를 유지하도록 보장하는 데 도움이 됩니다.

7. 패키지에 서명하기

패키지에 서명하여 진위와 무결성을 확인하세요. 이는 악의적인 행위자가 변조된 패키지를 배포하는 것을 방지하는 데 도움이 됩니다. gpg나 keyring과 같은 도구를 사용하여 패키지에 서명하세요.

고급 휠(Wheel) 기술

더 고급 사용 사례를 위해 다음 기술을 고려해 보세요:

1. build 사용하기

build 패키지는 파이썬 패키지를 빌드하는 현대적이고 표준화된 방법을 제공합니다. 휠과 소스 배포판을 모두 지원하며 setuptools보다 간단한 인터페이스를 제공합니다.

pip install build
python -m build

2. 편집 가능 모드(Editable) 설치

편집 가능 모드 설치를 사용하면 소스 코드에 직접 연결되는 방식으로 패키지를 설치할 수 있습니다. 이는 개발에 유용하며, 소스 코드 변경 사항이 재설치 없이 설치된 패키지에 즉시 반영됩니다.

pip install -e .

3. 빌드 프로세스 사용자 정의하기

사용자 정의 빌드 스크립트를 정의하거나 Meson 또는 CMake와 같은 빌드 시스템을 사용하여 빌드 프로세스를 사용자 정의할 수 있습니다. 이를 통해 특정 컴파일러 플래그로 C 확장을 빌드하거나 외부 라이브러리에 연결하는 등 더 복잡한 빌드 시나리오를 처리할 수 있습니다.

4. auditwheel 사용하기

auditwheel 도구는 공유 라이브러리를 포함하는 리눅스 휠을 감사하고 복구하는 데 사용됩니다. 이는 휠이 광범위한 리눅스 배포판에서 실행되는 데 필요한 모든 의존성을 포함하도록 보장합니다.

pip install auditwheel
auditwheel repair dist/my_package-0.1.0-py39-linux_x86_64.whl

결론

휠 배포 형식은 효율적이고 신뢰할 수 있으며 안전한 패키지 배포를 목표로 하는 파이썬 개발자에게 필수적인 도구입니다. 이 가이드에 설명된 단계를 따르고 모범 사례를 채택함으로써 설치 프로세스를 간소화하고 빌드 도구에 대한 의존성을 줄이며 전반적인 사용자 경험을 개선하는 휠 패키지를 만들 수 있습니다. 오픈 소스 커뮤니티에 패키지를 배포하든 내부 애플리케이션을 배포하든, 휠 형식을 이해하고 활용하는 것은 모든 파이썬 개발자에게 귀중한 기술입니다. 파이썬이 계속 발전함에 따라 휠과 같은 현대적인 패키징 관행을 수용하면 프로젝트가 전 세계 사용자들이 접근하고 유지 관리할 수 있도록 보장됩니다.

이러한 관행을 수용함으로써 전 세계적으로 더 강력하고 접근성 높은 파이썬 생태계에 기여할 수 있습니다.